<HTML><HEAD><TITLE>remote_connect(?Address, ?Peer, ?InitGoal)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">External Interface</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>remote_connect(?Address, ?Peer, ?InitGoal)</H1>
Initiate a remote interface connection
<DL>
<DT><EM>Address</EM></DT>
<DD>Address for remote connection (Host/Port or variable)
</DD>
<DT><EM>Peer</EM></DT>
<DD>Remote Peer name (atom or variable)
</DD>
<DT><EM>InitGoal</EM></DT>
<DD>Initialisation Goal (goal or variable)
</DD>
</DL>
<H2>Description</H2>

       <P> 
       Initiate a remote interface connection and sets up a remote peer
       Peer. ECLiPSe will listen for a remote connection from another
       process at the Address. Address can be either a variable, or
       HostName/Port, where either HostName or Port can be variables. The
       host name and port number are printed on log_output so that the
       other process can use them. The other process must be able to form a
       remote interface connection with ECLiPSe.  When the predicate
       returns, the remote process will have attached to the ECLiPSe
       session.  This predicate will block until the remote connection
       is established, and the remote side hands over control.

       <P>
       Once the Address is printed by the predicate, this information can
       then be used on the remote side to establish the remote connection,
       according to the remote interface connection protocol described in
       the Embedding and Interfacing manual. Once the connection is
       established, the optional user initialisation is performed on the
       ECLiPSe side before any further interactions. This is specified by
       InitGoal: If InitGoal is not a variable, it gives the goal that will
       be executed for the initialisation. If InitGoal is a variable, then
       no user initialisation is done before the two sides can
       interact. Initially, the remote side has control after the
       connection, so the predicate will return only when the remote side
       hands over control. Note that the predicate will not fail even if
       InitGoal fails or aborts.

       <P>
       If Host and Port are initially not variables, they must be valid for
       forming a socket connection.

       <P>
       This predicate is implemented by remote_connect_setup/3 and
       remote_connect_accept/6. These two predicates can be used to
       implement the remote connection, allowing for more flexibility.

<H3>Modes and Determinism</H3><UL>
<LI>remote_connect(?, -, ?) is det
<LI>remote_connect(?, +, ?) is semidet
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
Peer is an existing peer name.
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Host, Port or Peer not of correct type
<DT><EM>(141) unimplemented functionality </EM>
<DD>The remote protocols of the remote and ECLiPSe sides are incompatible.
<DT><EM>(170) system interface error </EM>
<DD>Port is not a valid port number
</DL>
<H2>Examples</H2>
<PRE>

% with the following definition for disconnect/0
disconnect :- writeln(bye).

% the following will cause `bye' to be printed when the remote connection
% is disconnected

remote_connect(_Address, Peer, set_event_handler(Control, disconnect/0)).
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/externals/remote_disconnect-1.html">remote_disconnect / 1</A>, <A HREF="../../kernel/externals/remote_yield-1.html">remote_yield / 1</A>, <A HREF="../../kernel/externals/remote_connect_setup-3.html">remote_connect_setup / 3</A>, <A HREF="../../kernel/externals/remote_connect_accept-6.html">remote_connect_accept / 6</A>
</BODY></HTML>
